

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>General Concepts &mdash; tdldk  documentation</title>
  

  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="tdldk  documentation" href="index.html"/>
        <link rel="next" title="TDLDK API 1.0 Reference" href="tdldk_1.0_reference.html"/>
        <link rel="prev" title="License" href="license.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-nav-search">
        

        
          <a href="index.html" class="icon icon-home"> tdldk
        

        
          
          <img src="_static/logo.png" class="logo" />
        
        </a>

        
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

        
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        
          
          
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">General Concepts</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#nurestsession">NURESTSession</a></li>
<li class="toctree-l2"><a class="reference internal" href="#nurestobject">NURESTObject</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#rest-names">ReST Names</a></li>
<li class="toctree-l3"><a class="reference internal" href="#rest-api-uri-generation">ReST API URI Generation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#exposing-rest-attributes">Exposing ReST Attributes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#crud-operations">CRUD Operations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#converting-to-and-from-a-python-dictionary">Converting to and from a Python Dictionary</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#nurestfetcher">NURESTFetcher</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#fetching-children-list">Fetching Children List</a></li>
<li class="toctree-l3"><a class="reference internal" href="#discussion-about-fetchers">Discussion about Fetchers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#nurestpushcenter">NURESTPushCenter</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#using-the-nurestpushcenter">Using the NURESTPushCenter</a></li>
<li class="toctree-l3"><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#conclusion">Conclusion</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tdldk_1.0_reference.html">TDLDK API 1.0 Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.galist.html">GAList</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.galist.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.galist.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.galist.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.galist.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.garoot.html">GARoot</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.garoot.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.garoot.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.gatask.html">GATask</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatask.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatask.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatask.html#constants">Constants</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatask.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatask.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.gatdlsession.html">GATDLSession</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatdlsession.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatdlsession.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatdlsession.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gatdlsession.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.gauser.html">GAUser</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gauser.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gauser.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.gauser.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/models.sdkinfo.html">SDKInfo</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/models.sdkinfo.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/fetchers.galistsfetcher.html">GAListsFetcher</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.galistsfetcher.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.galistsfetcher.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.galistsfetcher.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/fetchers.gatasksfetcher.html">GATasksFetcher</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gatasksfetcher.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gatasksfetcher.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gatasksfetcher.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tdldk/1.0/fetchers.gausersfetcher.html">GAUsersFetcher</a><ul>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gausersfetcher.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gausersfetcher.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="tdldk/1.0/fetchers.gausersfetcher.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="bambou_reference.html">Bambou API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.bambouconfig.html">BambouConfig</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.bambouconfig.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestconnection.html">NURESTConnection</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestconnection.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestconnection.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestfetcher.html">NURESTFetcher</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestfetcher.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestfetcher.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestlogincontroller.html">NURESTLoginController</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestlogincontroller.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestlogincontroller.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestmodelcontroller.html">NURESTModelController</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestmodelcontroller.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestobject.html">NURESTObject</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestobject.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestobject.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestpushcenter.html">NURESTPushCenter</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestpushcenter.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestpushcenter.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestrequest.html">NURESTRequest</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrequest.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrequest.html#methods">Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestresponse.html">NURESTResponse</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestresponse.html#properties">Properties</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestrootobject.html">NURESTRootObject</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrootobject.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrootobject.html#methods">Methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrootobject.html#inherited-properties">Inherited Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestrootobject.html#inherited-methods">Inherited Methods</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bambou/bambou.nurestsession.html">NURESTSession</a><ul>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestsession.html#properties">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="bambou/bambou.nurestsession.html#methods">Methods</a></li>
</ul>
</li>
</ul>
</li>
</ul>

          
        
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="index.html">tdldk</a>
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="index.html">Docs</a> &raquo;</li>
      
    <li>General Concepts</li>
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="_sources/general_concepts.txt" rel="nofollow"> View page source</a>
          
        
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document">
            
  <div class="section" id="general-concepts">
<h1>General Concepts<a class="headerlink" href="#general-concepts" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p><cite>tdldk</cite> provides a set of objects that allow the manipulation of ToDoList entities very easily. It deals with all possible CRUD operations. It is based on the library <cite>Bambou</cite>, which defines all these low level operations in a single place.</p>
<p>You will never use <cite>Bambou</cite> directly when working with <cite>tdldk</cite>. However, you need to understand the basics of this library because this is where all the concepts are defined. <cite>tdldk</cite> objects are simple autogenerated objects that all inherit from the same <cite>Bambou</cite> class and so, they all work the same.</p>
<p><cite>Bambou</cite> is composed of the following important classes:</p>
<ul>
<li><dl class="first docutils">
<dt><a class="reference internal" href="#nurestsession">NURESTSession</a></dt>
<dd><p class="first last">Class representing an authenticated session.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><a class="reference internal" href="#nurestobject">NURESTObject</a></dt>
<dd><p class="first last">Parent class of all ReST entities. All <cite>tdldk</cite> objects inherit from this class.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><a class="reference internal" href="#nurestfetcher">NURESTFetcher</a></dt>
<dd><p class="first last">Class used to get children of a <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a>.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><a class="reference internal" href="#nurestpushcenter">NURESTPushCenter</a></dt>
<dd><p class="first last">Class that deals with intercepting and rerouting ToDoList ReST Push Notifications.</p>
</dd>
</dl>
</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">There are more objects in <cite>Bambou</cite>, but you don&#8217;t need to know all of them for now.</p>
</div>
</div>
<div class="section" id="nurestsession">
<h2>NURESTSession<a class="headerlink" href="#nurestsession" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="bambou/bambou.nurestsession.html#bambou.NURESTSession" title="bambou.NURESTSession"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTSession</span></code></a> represents some user credentials coupled with an API URL. All ReST calls are done using the current active session. <a class="reference internal" href="bambou/bambou.nurestsession.html#bambou.NURESTSession" title="bambou.NURESTSession"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTSession</span></code></a> is an abstract class that must be reimplemented by anything using <cite>Bambou</cite>.</p>
<p>In <cite>tdldk</cite>, you use a class named <code class="xref py py-class docutils literal"><span class="pre">{sdk_name</span> <span class="pre">}}.v3_2.Session</span></code> which will be used in the following examples.</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">session</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">&quot;user&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">&quot;secret&quot;</span><span class="p">,</span> <span class="n">enterprise</span><span class="o">=</span><span class="s">&quot;organization&quot;</span><span class="p">,</span> <span class="n">api_url</span><span class="o">=</span><span class="s">&quot;https://todolist:8443&quot;</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

<span class="c"># your script</span>
</pre></div>
</td></tr></table></div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since August 2015, it is no longer necessary to provide the API version parameter. <cite>vpsk</cite> will automatically grab it from the <cite>tdldk</cite> you are using.</p>
</div>
<p>When you start the session, a ReST call will be sent to the API endpoint in order to get the ToDoList API key. If the credentials are valid, the attribute <code class="xref py py-attr docutils literal"><span class="pre">tdldk.v3_2.Session.user</span></code> will be populated with information such as your name, your phone number, your avatar, your enterprise name and ID etc. This <cite>user</cite> is the root object of everything as all subsequent calls need to be done in the context of your account (for instance, your <cite>/enterprises</cite> are different from another account&#8217;s <cite>/enterprises</cite>)</p>
<p>It is also possible to create sub sessions with the python statement <cite>with</cite>:</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">cspsession</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">&quot;user&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">&quot;secret&quot;</span><span class="p">,</span> <span class="n">enterprise</span><span class="o">=</span><span class="s">&quot;organization&quot;</span><span class="p">,</span> <span class="n">api_url</span><span class="o">=</span><span class="s">&quot;https://todolist:8443&quot;</span><span class="p">)</span>
<span class="n">adminsession</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">&quot;admin&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">&quot;secret&quot;</span><span class="p">,</span> <span class="n">enterprise</span><span class="o">=</span><span class="s">&quot;enterprise&quot;</span><span class="p">,</span> <span class="n">api_url</span><span class="o">=</span><span class="s">&quot;https://todolist:8443&quot;</span><span class="p">)</span>

<span class="n">cspsession</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

<span class="c"># this part of the code will use the CSP root user</span>

<span class="k">with</span> <span class="n">adminsession</span><span class="o">.</span><span class="n">start</span><span class="p">():</span>
    <span class="c"># this code block will be executed as admin of `enterprise`</span>

<span class="c"># back to csp root session</span>
</pre></div>
</td></tr></table></div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You <strong>must</strong> use <cite>start()</cite> when using the <cite>with</cite> statement, even if the session has already been started in the main context.</p>
</div>
</div>
<div class="section" id="nurestobject">
<h2>NURESTObject<a class="headerlink" href="#nurestobject" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> is the parent class of all <cite>tdldk</cite> entities.</p>
<div class="section" id="rest-names">
<h3>ReST Names<a class="headerlink" href="#rest-names" title="Permalink to this headline">¶</a></h3>
<p>All <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> subclasses implements a given method that will return the actual ReST name of the objects. For instance, the ReST name of an Unicorn object is <cite>unicorn</cite>.</p>
<p>These names are used to forge the correct URI when doing CRUD operations on them.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">ReST names can be used as unique resource identifier for a given object.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">ReST names are auto generated. You never need to manually define them.</p>
</div>
</div>
<div class="section" id="rest-api-uri-generation">
<h3>ReST API URI Generation<a class="headerlink" href="#rest-api-uri-generation" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> is able to forge all the URI needed to interact with the server through the ReST API.</p>
<p>For instance, if an object with a ReST name set to <cite>object</cite> needs to get the list of children with ReST name set to <cite>subobject</cite>, <cite>Bambou</cite> will use the following endpoint URL:</p>
<blockquote>
<div><cite>GET {api_base_url}/objects/{id}/subobjects</cite></div></blockquote>
<p>If an object with a ReST name set to <cite>entity</cite> needs to fetch itself, the generated URL will be</p>
<blockquote>
<div><cite>GET {api_base_url}/entities/{id}</cite></div></blockquote>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><cite>Bambou</cite> automagically deals with plurals.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The ReST base URL is pulled from the current active <a class="reference internal" href="bambou/bambou.nurestsession.html#bambou.NURESTSession" title="bambou.NURESTSession"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTSession</span></code></a>.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">URI are auto generated. You never need to deal with them manually.</p>
</div>
</div>
<div class="section" id="exposing-rest-attributes">
<h3>Exposing ReST Attributes<a class="headerlink" href="#exposing-rest-attributes" title="Permalink to this headline">¶</a></h3>
<p>Exposed attributes will be converted and sent to the server when you do CRUD operations. That way, if an object has an attribute <code class="xref py py-attr docutils literal"><span class="pre">name</span></code>, it can be marked as a ReST attribute.</p>
<p>When saving the object, the value of <code class="xref py py-attr docutils literal"><span class="pre">name</span></code> will be put into the generated JSON structure that will be sent to the server, or automatically populated from a JSON structure that is coming from the server.</p>
<p>Not only the attribute can be exposed, but also its type and other informations like if it is read only, its allowed values, its format, its default value and so on.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">exposing ReST Attributes is auto generated. You never need to manually expose new attributes.</p>
</div>
</div>
<div class="section" id="crud-operations">
<h3>CRUD Operations<a class="headerlink" href="#crud-operations" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> allows to perform all sorts of CRUD operations.</p>
<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">fetch</code><span class="sig-paren">(</span><em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.fetch"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Fetch all information about the current object</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>async</strong> (<em>bool</em>) &#8211; Boolean to make an asynchronous call. Default is False</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback method that will be triggered in case of asynchronous call</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">(current_fetcher, callee_parent, fetched_bjects, connection)</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">tuple</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span> <span class="o">=</span> <span class="n">NUEntity</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;xxx-xxx-xxx-xxx&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span> <span class="c"># will get the entity with id &quot;xxx-xxx-xxx-xxx&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">name</span>
<span class="go">&quot;My Entity&quot;</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">save</code><span class="sig-paren">(</span><em>response_choice=None</em>, <em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.save"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Update object and call given callback in case of async call</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>async</strong> (<em>bool</em>) &#8211; Boolean to make an asynchronous call. Default is False</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback method that will be triggered in case of asynchronous call</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">&quot;My Super Object&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">save</span><span class="p">()</span> <span class="c"># will save the new name in the server</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">delete</code><span class="sig-paren">(</span><em>response_choice=1</em>, <em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.delete"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Delete object and call given callback in case of call.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>response_choice</strong> (<em>int</em>) &#8211; Automatically send a response choice when confirmation is needed</li>
<li><strong>async</strong> (<em>bool</em>) &#8211; Boolean to make an asynchronous call. Default is False</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback method that will be triggered in case of asynchronous call</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span> <span class="c"># will delete the enterprise from the server</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">create_child</code><span class="sig-paren">(</span><em>nurest_object</em>, <em>response_choice=None</em>, <em>async=False</em>, <em>callback=None</em>, <em>commit=True</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.create_child"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Add given nurest_object to the current object</p>
<p>For example, to add a child into a parent, you can call
parent.create_child(nurest_object=child)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>nurest_object</strong> (<a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><em>bambou.NURESTObject</em></a>) &#8211; the NURESTObject object to add</li>
<li><strong>response_choice</strong> (<em>int</em>) &#8211; Automatically send a response choice when confirmation is needed</li>
<li><strong>async</strong> (<em>bool</em>) &#8211; should the request be done asynchronously or not</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; callback containing the object and the connection</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">Returns the object and connection (object, connection)</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span> <span class="o">=</span> <span class="n">NUEntity</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;Super Entity&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parent_entity</span><span class="o">.</span><span class="n">create_child</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span> <span class="c"># the new entity as been created in the parent_entity</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">assign</code><span class="sig-paren">(</span><em>objects</em>, <em>nurest_object_type</em>, <em>async=False</em>, <em>callback=None</em>, <em>commit=True</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.assign"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Reference a list of objects into the current resource</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>objects</strong> (<em>list</em>) &#8211; list of NURESTObject to link</li>
<li><strong>nurest_object_type</strong> (<em>type</em>) &#8211; Type of the object to link</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback method that should be fired at the end</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">Returns the current object and the connection (object, connection)</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">assign</span><span class="p">([</span><span class="n">entity1</span><span class="p">,</span> <span class="n">entity2</span><span class="p">,</span> <span class="n">entity3</span><span class="p">],</span> <span class="n">NUEntity</span><span class="p">)</span> <span class="c"># entity1, entity2 and entity3 are now part of the entity</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">instantiate_child</code><span class="sig-paren">(</span><em>nurest_object</em>, <em>from_template</em>, <em>response_choice=None</em>, <em>async=False</em>, <em>callback=None</em>, <em>commit=True</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.instantiate_child"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Instantiate an nurest_object from a template object</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>nurest_object</strong> &#8211; the NURESTObject object to add</li>
<li><strong>from_template</strong> &#8211; the NURESTObject template object</li>
<li><strong>callback</strong> &#8211; callback containing the object and the connection</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">Returns the object and connection (object, connection)</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">parent_entity</span> <span class="o">=</span> <span class="n">NUParentEntity</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;xxxx-xxxx-xxx-xxxx&quot;</span><span class="p">)</span> <span class="c"># create a NUParentEntity with an existing ID (or retrieve one)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">other_entity_template</span> <span class="o">=</span> <span class="n">NUOtherEntityTemplate</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;yyyy-yyyy-yyyy-yyyy&quot;</span><span class="p">)</span> <span class="c"># create a NUOtherEntityTemplate with an existing ID (or retrieve one)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">other_entity_instance</span> <span class="o">=</span> <span class="n">NUOtherEntityInstance</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;my new instance&quot;</span><span class="p">)</span> <span class="c"># create a new NUOtherEntityInstance to be intantiated from other_entity_template</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parent_entity</span><span class="o">.</span><span class="n">instantiate_child</span><span class="p">(</span><span class="n">other_entity_instance</span><span class="p">,</span> <span class="n">other_entity_template</span><span class="p">)</span> <span class="c"># instatiate the new domain in the server</span>
</pre></div>
</div>
</dd></dl>

<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All these methods require the current <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> to have a valid <code class="xref py py-attr docutils literal"><span class="pre">bambou.NURESTObject.ID</span></code>.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may notice that there is no creation method. Creation is always happening from a parent object and is done using <cite>create_child</cite>.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may notice that an optional parameter <code class="xref py py-attr docutils literal"><span class="pre">callback</span></code> is present. This is because <cite>tdldk</cite> can work completely asynchronously.</p>
</div>
</div>
<div class="section" id="converting-to-and-from-a-python-dictionary">
<h3>Converting to and from a Python Dictionary<a class="headerlink" href="#converting-to-and-from-a-python-dictionary" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> allows quick and easy conversion from and to python dictionaries</p>
<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">from_dict</code><span class="sig-paren">(</span><em>dictionary</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.from_dict"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Sets all the exposed ReST attribues from the given dictionary</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>dictionary</strong> (<em>dict</em>) &#8211; dictionnary containing the raw object attributes and their values.</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">info</span> <span class="o">=</span> <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;my group&quot;</span><span class="p">,</span> <span class="s">&quot;private&quot;</span><span class="p">:</span> <span class="bp">False</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">NUGroup</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">info</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="s">&quot;name: </span><span class="si">%s</span><span class="s"> - private: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">group</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">group</span><span class="o">.</span><span class="n">private</span><span class="p">)</span>
<span class="go">&quot;name: my group - private: False&quot;</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">to_dict</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.to_dict"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Converts the current object into a Dictionary using all exposed ReST attributes.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">the dictionary containing all the exposed ReST attributes and their values.</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">dict</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">to_dict</span><span class="p">()</span>
<span class="go">{&quot;name&quot;: &quot;my entity&quot;, &quot;description&quot;: &quot;Hello World&quot;, &quot;ID&quot;: &quot;xxxx-xxx-xxxx-xxx&quot;, ...}</span>
</pre></div>
</div>
</dd></dl>

<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">you never need to process to the actual JSON conversion when sending info to the server. <a class="reference internal" href="bambou/bambou.nurestconnection.html#bambou.NURESTConnection" title="bambou.NURESTConnection"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTConnection</span></code></a> will do that automatically, but you can use these methods to print an object, or copy information of an object into one another.</p>
</div>
</div>
</div>
<div class="section" id="nurestfetcher">
<h2>NURESTFetcher<a class="headerlink" href="#nurestfetcher" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="bambou/bambou.nurestfetcher.html#bambou.NURESTFetcher" title="bambou.NURESTFetcher"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTFetcher</span></code></a> is a class allowing a <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> to fetch its children. All <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> have one or more fetchers, unless it&#8217;s a final object in the ToDoList model hierarchy. <a class="reference internal" href="bambou/bambou.nurestfetcher.html#bambou.NURESTFetcher" title="bambou.NURESTFetcher"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTFetcher</span></code></a> provides a lot of possibility regarding the way you want to get a given children list. It can deal with simple object fetching, pagination, filtering, request headers, grouping etc.</p>
<div class="section" id="fetching-children-list">
<h3>Fetching Children List<a class="headerlink" href="#fetching-children-list" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="bambou/bambou.nurestfetcher.html#bambou.NURESTFetcher" title="bambou.NURESTFetcher"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTFetcher</span></code></a> has three importants methods:</p>
<dl class="method">
<dt>
<code class="descclassname">NURESTFetcher.</code><code class="descname">fetch</code><span class="sig-paren">(</span><em>filter=None</em>, <em>order_by=None</em>, <em>group_by=[]</em>, <em>page=None</em>, <em>page_size=None</em>, <em>query_parameters=None</em>, <em>commit=True</em>, <em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_fetcher.html#NURESTFetcher.fetch"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Fetch objects according to given filter and page.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This method fetches all managed class objects and store them
in local_name of the served object. which means that the parent
object will hold them in a list. You can prevent this behavior
by setting commit to False. In that case, the fetched children
won&#8217;t be added in the parent object cache.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>filter</strong> (<em>string</em>) &#8211; string that represents a predicate filter</li>
<li><strong>order_by</strong> (<em>string</em>) &#8211; string that represents an order by clause</li>
<li><strong>group_by</strong> (<em>string</em>) &#8211; list of names for grouping</li>
<li><strong>page</strong> (<em>int</em>) &#8211; number of the page to load</li>
<li><strong>page_size</strong> (<em>int</em>) &#8211; number of results per page</li>
<li><strong>commit</strong> (<em>bool</em>) &#8211; boolean to update current object</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback that should be called in case of a async request</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Returns a tuple of information (fetcher, served object, fetched objects, connection)</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">tuple</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">children</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span>
<span class="go">(&lt;NUChildrenFetcher at aaaa&gt;, &lt;NUEntity at bbbb&gt;, [&lt;NUChildren at ccc&gt;, &lt;NUChildren at ddd&gt;], &lt;NURESTConnection at zzz&gt;)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTFetcher.</code><code class="descname">get</code><span class="sig-paren">(</span><em>filter=None</em>, <em>order_by=None</em>, <em>group_by=[]</em>, <em>page=None</em>, <em>page_size=None</em>, <em>query_parameters=None</em>, <em>commit=True</em>, <em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_fetcher.html#NURESTFetcher.get"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Fetch object and directly return them</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><cite>get</cite> won&#8217;t put the fetched objects in the parent&#8217;s children list.
You cannot override this behavior. If you want to commit them in the parent
you can use :method:vsdk.NURESTFetcher.fetch or manually add the list with
:method:vsdk.NURESTObject.add_child</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>filter</strong> (<em>string</em>) &#8211; string that represents a predicate filter</li>
<li><strong>order_by</strong> (<em>string</em>) &#8211; string that represents an order by clause</li>
<li><strong>group_by</strong> (<em>string</em>) &#8211; list of names for grouping</li>
<li><strong>page</strong> (<em>int</em>) &#8211; number of the page to load</li>
<li><strong>page_size</strong> (<em>int</em>) &#8211; number of results per page</li>
<li><strong>commit</strong> (<em>bool</em>) &#8211; boolean to update current object</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback that should be called in case of a async request</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">list of vsdk.NURESTObject if any</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">list</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">children</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
<span class="go">[&lt;NUChildren at xxx&gt;, &lt;NUChildren at yyyy&gt;, &lt;NUChildren at zzz&gt;]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTFetcher.</code><code class="descname">get_first</code><span class="sig-paren">(</span><em>filter=None</em>, <em>order_by=None</em>, <em>group_by=[]</em>, <em>query_parameters=None</em>, <em>commit=False</em>, <em>async=False</em>, <em>callback=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_fetcher.html#NURESTFetcher.get_first"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Fetch object and directly return the first one</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><cite>get_first</cite> won&#8217;t put the fetched object in the parent&#8217;s children list.
You cannot override this behavior. If you want to commit it in the parent
you can use :method:vsdk.NURESTFetcher.fetch or manually add it with
:method:vsdk.NURESTObject.add_child</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>filter</strong> (<em>string</em>) &#8211; string that represents a predicate filter</li>
<li><strong>order_by</strong> (<em>string</em>) &#8211; string that represents an order by clause</li>
<li><strong>group_by</strong> (<em>string</em>) &#8211; list of names for grouping</li>
<li><strong>page</strong> (<em>int</em>) &#8211; number of the page to load</li>
<li><strong>page_size</strong> (<em>int</em>) &#8211; number of results per page</li>
<li><strong>commit</strong> (<em>bool</em>) &#8211; boolean to update current object</li>
<li><strong>callback</strong> (<em>function</em>) &#8211; Callback that should be called in case of a async request</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">the first object if any, or None</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">vsdk.NURESTObject</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">children</span><span class="o">.</span><span class="n">get_first</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="s">&quot;name == &#39;My Entity&#39;&quot;</span><span class="p">)</span>
<span class="go">&lt;NUChildren at xxx&gt;</span>
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="discussion-about-fetchers">
<h3>Discussion about Fetchers<a class="headerlink" href="#discussion-about-fetchers" title="Permalink to this headline">¶</a></h3>
<p>Fetcher is a powerfull concept that makes the process of getting child objects completely generic and code friendly. <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> provides methods that allow to deal programatically with its fetchers in a completely generic way.</p>
<dl class="method">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">fetcher_for_rest_name</code><span class="sig-paren">(</span><em>rest_name</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_object.html#NURESTObject.fetcher_for_rest_name"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Returns the children fetcher for the given rest name</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>rest_name</strong> (<em>string</em>) &#8211; the children rest name</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">Returns the corresponding fetcher</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">list</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">fetcher_for_rest_name</span><span class="p">(</span><span class="n">NUSubEntity</span><span class="o">.</span><span class="n">rest_name</span><span class="p">)</span>
<span class="go">&lt;NUSubEntitiesFetcher at yyyy&gt;</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">fetchers</code></dt>
<dd><p>Return a copy of all fetchers</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">list of all fetchers</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">list</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">entity</span><span class="o">.</span><span class="n">fetchers</span>
<span class="go">[&lt;NUSubEntitiesFetcher at xxxx&gt;, &lt;NUOtherEntitiesFetcher at yyyy&gt;]</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descclassname">NURESTObject.</code><code class="descname">children_rest_names</code></dt>
<dd><p>Gets the list of all possible children ReST names.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">list containing all possible rest names as string</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">list</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span> <span class="o">=</span> <span class="n">NUEntity</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">entity</span><span class="o">.</span><span class="n">children_rest_names</span>
<span class="go">[&quot;foo&quot;, &quot;bar&quot;]</span>
</pre></div>
</div>
</dd></dl>

<p>This allows complete abstract programatic operations on any objects.</p>
<p>For instance, the following function will create a new <code class="xref py py-class docutils literal"><span class="pre">tdldk.v3_2.Metadata</span></code> to the entire hierarchy of children from a given object that has been created after a certain date:</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">def</span> <span class="nf">apply_metatada_to_all_children</span><span class="p">(</span><span class="n">root_object</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>

    <span class="c"># Loop on all declared children fetchers</span>
    <span class="k">for</span> <span class="n">fetcher</span> <span class="ow">in</span> <span class="n">root_object</span><span class="o">.</span><span class="n">fetchers</span><span class="p">:</span>

        <span class="c"># Fetch the list of the children</span>
        <span class="n">children</span> <span class="o">=</span> <span class="n">fetcher</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="nb">filter</span><span class="p">)</span>

        <span class="c"># Loop on all fetched children</span>
        <span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">children</span><span class="p">:</span>

            <span class="c"># Add the metadata to the current children</span>
            <span class="n">child</span><span class="o">.</span><span class="n">create_child</span><span class="p">(</span><span class="n">metadata</span><span class="p">)</span>

            <span class="c"># Start over recursively on the children of the current child</span>
            <span class="n">apply_metadata_to_all_children</span><span class="p">(</span><span class="n">child</span><span class="p">,</span> <span class="n">metadata</span><span class="p">)</span>


<span class="n">enterprise</span> <span class="o">=</span> <span class="n">Enterprise</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;xxxx-xxxx-xxx-xxxx&quot;</span><span class="p">)</span>
<span class="n">metadata</span> <span class="o">=</span> <span class="n">Metadata</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;my metadata&quot;</span><span class="p">,</span> <span class="n">blob</span><span class="o">=</span><span class="s">&quot;hello world!&quot;</span><span class="p">)</span>

<span class="n">apply_metadata_to_all_children</span><span class="p">(</span><span class="n">enterprise</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s">&quot;creationDate &gt; &#39;01-01-2015&#39;&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</div>
<div class="section" id="nurestpushcenter">
<h2>NURESTPushCenter<a class="headerlink" href="#nurestpushcenter" title="Permalink to this headline">¶</a></h2>
<p>The ToDoList API supports client side push through a long polling connection. ReST clients can connect to that channel and will get a notification as soon as he or someone else in the system changes something. This events are filtered by permissions, which means that if someone change a property of an object you cannot see, you won&#8217;t get notified. <cite>tdldk</cite> provides the <a class="reference internal" href="bambou/bambou.nurestpushcenter.html#bambou.NURESTPushCenter" title="bambou.NURESTPushCenter"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTPushCenter</span></code></a>, which encapsulates all the logic to deal with the event channel. It runs in its own thread and will call registered callbacks when it receives a push.</p>
<p>A <a class="reference internal" href="bambou/bambou.nurestpushcenter.html#bambou.NURESTPushCenter" title="bambou.NURESTPushCenter"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTPushCenter</span></code></a> is automatically created with each <a class="reference internal" href="bambou/bambou.nurestsession.html#bambou.NURESTSession" title="bambou.NURESTSession"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTSession</span></code></a> and it is available from the attribute <a class="reference internal" href="bambou/bambou.nurestsession.html#bambou.NURESTSession.push_center" title="bambou.NURESTSession.push_center"><code class="xref py py-attr docutils literal"><span class="pre">bambou.NURESTSession.push_center</span></code></a>.</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">session</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">&quot;user&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">&quot;secret&quot;</span><span class="p">,</span> <span class="n">enterprise</span><span class="o">=</span><span class="s">&quot;organization&quot;</span><span class="p">,</span> <span class="n">api_url</span><span class="o">=</span><span class="s">&quot;https://todolist:8443&quot;</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="n">session</span><span class="o">.</span><span class="n">push_center</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
</pre></div>
</td></tr></table></div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You need to explicitely start the push center.</p>
</div>
<div class="section" id="using-the-nurestpushcenter">
<h3>Using the NURESTPushCenter<a class="headerlink" href="#using-the-nurestpushcenter" title="Permalink to this headline">¶</a></h3>
<p>Only the following methods are important:</p>
<dl class="method">
<dt>
<code class="descclassname">NURESTPushCenter.</code><code class="descname">start</code><span class="sig-paren">(</span><em>timeout=None</em>, <em>root_object=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_push_center.html#NURESTPushCenter.start"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Starts listening to events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>timeout</strong> (<em>int</em>) &#8211; number of seconds before timeout. Used for testing purpose only.</li>
<li><strong>root_object</strong> (<a class="reference internal" href="bambou/bambou.nurestrootobject.html#bambou.NURESTRootObject" title="bambou.NURESTRootObject"><em>bambou.NURESTRootObject</em></a>) &#8211; NURESTRootObject object that is listening. Used for testing purpose only.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTPushCenter.</code><code class="descname">add_delegate</code><span class="sig-paren">(</span><em>callback</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_push_center.html#NURESTPushCenter.add_delegate"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Registers a new delegate callback</p>
<p>The prototype should be function(data), where data will be the decoded json push</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>callback</strong> (<em>function</em>) &#8211; method to trigger when push center receives events</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descclassname">NURESTPushCenter.</code><code class="descname">remove_delegate</code><span class="sig-paren">(</span><em>callback</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/bambou/nurest_push_center.html#NURESTPushCenter.remove_delegate"><span class="viewcode-link">[source]</span></a></dt>
<dd><p>Unregisters a registered delegate function or a method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>callback</strong> (<em>function</em>) &#8211; method to trigger when push center receives events</td>
</tr>
</tbody>
</table>
</dd></dl>

</div>
<div class="section" id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>Here is a really simple code sample that will print the push data on every push:</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16</pre></div></td><td class="code"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">tdldk</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pprint</span>
<span class="kn">from</span> <span class="nn">time</span> <span class="kn">import</span> <span class="n">sleep</span>

<span class="n">session</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">&quot;csproot&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">&quot;secret&quot;</span><span class="p">,</span> <span class="n">enterprise</span><span class="o">=</span><span class="s">&quot;csp&quot;</span><span class="p">,</span> <span class="n">api_url</span><span class="o">=</span><span class="s">&quot;https://todolist:8443&quot;</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

<span class="k">def</span> <span class="nf">on_receive_push</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="n">pprint</span><span class="p">(</span><span class="n">data</span><span class="p">);</span>

<span class="n">session</span><span class="o">.</span><span class="n">push_center</span><span class="o">.</span><span class="n">add_delegate</span><span class="p">(</span><span class="n">on_receive_push</span><span class="p">);</span>
<span class="n">session</span><span class="o">.</span><span class="n">push_center</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

<span class="c"># default stupid run loop. don&#39;t do that in real life :)</span>
<span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
    <span class="n">sleep</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
</div>
</div>
<div class="section" id="conclusion">
<h2>Conclusion<a class="headerlink" href="#conclusion" title="Permalink to this headline">¶</a></h2>
<p>Now you know the basics of <cite>Bambou</cite> and so, of the <cite>tdldk</cite>. Remember that all objects in <cite>tdldk</cite> are subclasses of <a class="reference internal" href="bambou/bambou.nurestobject.html#bambou.NURESTObject" title="bambou.NURESTObject"><code class="xref py py-class docutils literal"><span class="pre">bambou.NURESTObject</span></code></a> so they <strong>all</strong> work exactly the same.</p>
<p>There is a lot more to know about <cite>Bambou</cite> like the asynchronous mode, auto model parsing, easy controllers creation thanks introspection and so on. We&#8217;ll cover this in a different advanced section.</p>
</div>
</div>


          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="tdldk_1.0_reference.html" class="btn btn-neutral float-right" title="TDLDK API 1.0 Reference" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="license.html" class="btn btn-neutral" title="License" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright Copyright (c) 2015, Nuage Networks.
    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>